<!DOCTYPE html>
<html>
<head>
	<!-- Global site tag (gtag.js) - Google Analytics -->
	<script async src="https://www.googletagmanager.com/gtag/js?id='UA-133422980-2"></script>
	<script>
	  window.dataLayer = window.dataLayer || [];
	  function gtag(){dataLayer.push(arguments);}
	  gtag('js', new Date());

	  gtag('config', 'UA-133422980-2');
	</script>

	<meta charset="utf-8">
	<meta http-equiv="x-ua-compatible" content="ie=edge">
	<meta name="viewport" content="width=device-width, initial-scale=1">

	<title>
		gem5: Building gem5 
	</title>

	<!-- SITE FAVICON -->
	<link rel="shortcut icon" type="image/gif" href="/assets/img/gem5ColorVert.gif"/>

	<link rel="canonical" href="http://localhost:4000/documentation/learning_gem5/part1/building/">
	<link href='https://fonts.googleapis.com/css?family=Open+Sans:400,300,700,800,600' rel='stylesheet' type='text/css'>
	<link href='https://fonts.googleapis.com/css?family=Muli:400,300' rel='stylesheet' type='text/css'>

	<!-- FAVICON -->
	<link rel="stylesheet" href="//maxcdn.bootstrapcdn.com/font-awesome/4.3.0/css/font-awesome.min.css">

	<!-- BOOTSTRAP -->
	<link rel="stylesheet" href="https://stackpath.bootstrapcdn.com/bootstrap/4.1.3/css/bootstrap.min.css" integrity="sha384-MCw98/SFnGE8fJT3GXwEOngsV7Zt27NXFoaoApmYm81iuXoPkFOJwJ8ERdknLPMO" crossorigin="anonymous">

	<!-- CUSTOM CSS -->
	<link rel="stylesheet" href="/css/main.css">
</head>


<body>
	<nav class="navbar navbar-expand-md navbar-light bg-light">
  <a class="navbar-brand" href="/">
		<img src="/assets/img/gem5ColorLong.gif" alt="gem5" height=55px>
	</a>
  <button class="navbar-toggler" type="button" data-toggle="collapse" data-target="#navbarNavDropdown" aria-controls="navbarNavDropdown" aria-expanded="false" aria-label="Toggle navigation">
    <span class="navbar-toggler-icon"></span>
  </button>
  <div class="collapse navbar-collapse" id="navbarNavDropdown">
    <!-- LIST FOR NAVBAR -->
    <ul class="navbar-nav ml-auto">
      <!-- HOME -->
      <li class="nav-item ">
        <a class="nav-link" href="/">Home</a>
      </li>

      <!-- ABOUT -->
			<li class="nav-item dropdown ">
				<a class="nav-link dropdown-toggle" id="navbarDropdownMenuLink" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
					About
				</a>
				<div class="dropdown-menu" aria-labelledby="navbarDropdownMenuLink">
          <a class="dropdown-item" href="/about">About gem5</a>
          <a class="dropdown-item" href="/publications">Publications</a>
          <a class="dropdown-item" href="/governance">Governance</a>
				</div>
			</li>

      <!-- DOCUMENTATION -->
			<li class="nav-item dropdown active">
				<a class="nav-link dropdown-toggle" id="navbarDropdownMenuLink" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
					Documentation
				</a>
				<div class="dropdown-menu" aria-labelledby="navbarDropdownMenuLink">
					<!-- Pull navigation from _data/documentation.yml -->
					
            <a class="dropdown-item" href="/documentation">gem5 documentation</a>
					
            <a class="dropdown-item" href="/documentation/learning_gem5/introduction">Learning gem5</a>
					
            <a class="dropdown-item" href="http://doxygen.gem5.org/release/current/index.html">gem5 Doxygen</a>
					
            <a class="dropdown-item" href="/documentation/reporting_problems">Reporting Problems</a>
					
				</div>
			</li>

      <!-- EVENTS -->
			<li class="nav-item dropdown ">
        <a class="nav-link" href="/events/">Events</a>
			</li>

      <!-- CONTRIBUTING -->
      <li class="nav-item ">
        <a class="nav-link" href="/contributing">Contributing</a>
      </li>

      <!-- BLOG -->
      <li class="nav-item ">
        <a class="nav-link" href="/blog">Blog</a>
      </li>

      <!-- SEARCH -->
			<li class="nav-item ">
        <a class="nav-link" href="/search">Search</a>
      </li>
    </ul>
  </div>
</nav>

	<main>
		<div class="sidenav-top">
  <div class="sidenav-brand bg-light">
    <a href="/"><img src="/assets/img/gem5ColorLong.gif" height="55px"></a>
  </div>
  <div class="search">
    <form action="/search" method="get">
      <!-- <label for="search-box"><i class="fa fa-search"></i></label> -->
      <input type="text" name="query">
      <button type="submit" name="submit"><i class="fa fa-search"></i></button>
    </form>
  </div>
</div>
<div class="sidenav">
  <!-- Pull navigation from _data/documentation.yml -->
  
    
  
    
    
      <a class="item" href="/documentation/learning_gem5/introduction" role="button" aria-expanded="false" aria-controls="collapseExample">
        Introduction
      </a>
      <div class="collapse " id="introduction">
        
      </div>
    
      <a class="item" data-toggle="collapse" href="#part1" role="button" aria-expanded="false" aria-controls="collapseExample">
        Getting Started
      </a>
      <div class="collapse show" id="part1">
        
          <a class="subitem active" href="/documentation/learning_gem5/part1/building">Building gem5</a>
        
          <a class="subitem " href="/documentation/learning_gem5/part1/simple_config">Creating a simple configuration script</a>
        
          <a class="subitem " href="/documentation/learning_gem5/part1/cache_config">Adding cache to configuration script</a>
        
          <a class="subitem " href="/documentation/learning_gem5/part1/gem5_stats">Understanding gem5 statistics and output</a>
        
          <a class="subitem " href="/documentation/learning_gem5/part1/example_configs">Using the default configuration scripts</a>
        
      </div>
    
      <a class="item" data-toggle="collapse" href="#part2" role="button" aria-expanded="false" aria-controls="collapseExample">
        Modifying/Extending
      </a>
      <div class="collapse " id="part2">
        
          <a class="subitem " href="/documentation/learning_gem5/part2/environment">Setting up your development environment</a>
        
          <a class="subitem " href="/documentation/learning_gem5/part2/helloobject">Creating a very simple SimObject</a>
        
          <a class="subitem " href="/documentation/learning_gem5/part2/debugging">Debugging gem5</a>
        
          <a class="subitem " href="/documentation/learning_gem5/part2/events">Event-driven programming</a>
        
          <a class="subitem " href="/documentation/learning_gem5/part2/parameters">Adding parameters to SimObjects and more events</a>
        
          <a class="subitem " href="/documentation/learning_gem5/part2/memoryobject">Creating SimObjects in the memory system</a>
        
          <a class="subitem " href="/documentation/learning_gem5/part2/simplecache">Creating a simple cache object</a>
        
      </div>
    
      <a class="item" data-toggle="collapse" href="#part3" role="button" aria-expanded="false" aria-controls="collapseExample">
        Modeling Cache Coherence with Ruby
      </a>
      <div class="collapse " id="part3">
        
          <a class="subitem " href="/documentation/learning_gem5/part3/MSIintro">Introduction to Ruby</a>
        
          <a class="subitem " href="/documentation/learning_gem5/part3/cache-intro">MSI example cache protocol</a>
        
          <a class="subitem " href="/documentation/learning_gem5/part3/cache-declarations">Declaring a state machine</a>
        
          <a class="subitem " href="/documentation/learning_gem5/part3/cache-in-ports">In port code blocks</a>
        
          <a class="subitem " href="/documentation/learning_gem5/part3/cache-actions">Action code blocks</a>
        
          <a class="subitem " href="/documentation/learning_gem5/part3/cache-transitions">Transition code blocks</a>
        
          <a class="subitem " href="/documentation/learning_gem5/part3/directory">MSI Directory implementation</a>
        
          <a class="subitem " href="/documentation/learning_gem5/part3/MSIbuilding">Compiling a SLICC protocol</a>
        
          <a class="subitem " href="/documentation/learning_gem5/part3/configuration">Configuring a simple Ruby system</a>
        
          <a class="subitem " href="/documentation/learning_gem5/part3/running">Running the simple Ruby system</a>
        
          <a class="subitem " href="/documentation/learning_gem5/part3/MSIdebugging">Debugging SLICC Protocols</a>
        
          <a class="subitem " href="/documentation/learning_gem5/part3/simple-MI_example">Configuring for a standard protocol</a>
        
      </div>
    
      <a class="item" href="/documentation/learning_gem5/gem5_101/" role="button" aria-expanded="false" aria-controls="collapseExample">
        gem5 101
      </a>
      <div class="collapse " id="gem5_101">
        
      </div>
    
    
  
    
  
    
  
</div>


<div class="container" id="doc-container">
  <div class="edit"><a href="https://gem5.googlesource.com/public/gem5-website/+/refs/heads/master/README.md">Edit this page</a></div>
  <b>authors:</b> Jason Lowe-Power<br>
  

  <br>
  <h1 id="building-gem5">Building gem5</h1>

<p>This chapter covers the details of how to set up a gem5 developmment
environment and build gem5.</p>

<h2 id="requirements-for-gem5">Requirements for gem5</h2>

<p>See <a href="http://gem5.org/Compiling_M5#Required_Software">gem5 requirements</a>
for more details.</p>

<p>On Ubuntu, you can install all of the required dependencies with the
following command. The requirements are detailed below.</p>

<div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>sudo apt install build-essential git m4 scons zlib1g zlib1g-dev libprotobuf-dev protobuf-compiler libprotoc-dev libgoogle-perftools-dev python-dev python
</code></pre></div></div>

<ol>
  <li>
    <dl>
      <dt>git (<a href="https://git-scm.com/">Git</a>):</dt>
      <dd>The gem5 project uses <a href="https://git-scm.com/">Git</a> for version
control. <a href="https://git-scm.com/">Git</a> is a distributed version
control system. More information about
<a href="https://git-scm.com/">Git</a> can be found by following the link.
Git should be installed by default on most platforms. However,
to install Git in Ubuntu use

        <div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>sudo apt install git
</code></pre></div>        </div>
      </dd>
    </dl>
  </li>
  <li>
    <dl>
      <dt>gcc 4.8+</dt>
      <dd>You may need to use environment variables to point to a
non-default version of gcc.

        <p>On Ubuntu, you can install a development environment with</p>

        <div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>sudo apt install build-essential
</code></pre></div>        </div>
      </dd>
    </dl>
  </li>
  <li>
    <dl>
      <dt><a href="http://www.scons.org/">SCons</a></dt>
      <dd>gem5 uses SCons as its build environment. SCons is like make on
steroids and uses Python scripts for all aspects of the build
process. This allows for a very flexible (if slow) build system.

        <p>To get SCons on Ubuntu use</p>

        <div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>sudo apt install scons
</code></pre></div>        </div>
      </dd>
    </dl>
  </li>
  <li>
    <dl>
      <dt>Python 2.7+</dt>
      <dd>gem5 relies on the Python development libraries. To install
these on Ubuntu use

        <div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>sudo apt install python-dev
</code></pre></div>        </div>
      </dd>
    </dl>
  </li>
  <li>
    <dl>
      <dt><a href="https://developers.google.com/protocol-buffers/">protobuf</a> 2.1+</dt>
      <dd>“Protocol buffers are a language-neutral, platform-neutral
extensible mechanism for serializing structured data.” In gem5,
the <a href="https://developers.google.com/protocol-buffers/">protobuf</a>
library is used for trace generation and playback.
<a href="https://developers.google.com/protocol-buffers/">protobuf</a> is
not a required package, unless you plan on using it for trace
generation and playback.

        <div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>sudo apt install libprotobuf-dev python-protobuf protobuf-compiler libgoogle-perftools-dev
</code></pre></div>        </div>
      </dd>
    </dl>
  </li>
  <li>
    <p><a href="https://www.boost.org/">Boost</a> (<strong>Optional</strong>) : The Boost library is a set
     of general purpose C++ libraries. It is a necessary dependency if you
     wish to use the SystemC implementation.</p>

    <div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code> ```
 sudo apt install libboost-all-dev
 ```
</code></pre></div>    </div>
  </li>
</ol>

<h2 id="getting-the-code">Getting the code</h2>

<p>Change directories to where you want to download the gem5 source. Then,
to clone the repository, use the <code class="highlighter-rouge">git clone</code> command.</p>

<div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>git clone https://gem5.googlesource.com/public/gem5
</code></pre></div></div>

<p>You can now change directories to <code class="highlighter-rouge">gem5</code> which contains all of the gem5
code.</p>

<h2 id="your-first-gem5-build">Your first gem5 build</h2>

<p>Let’s start by building a basic x86 system. Currently, you must compile
gem5 separately for every ISA that you want to simulate. Additionally,
if using ruby-intro-chapter, you have to have separate compilations for
every cache coherence protocol.</p>

<p>To build gem5, we will use SCons. SCons uses the SConstruct file
(<code class="highlighter-rouge">gem5/SConstruct</code>) to set up a number of variables and then uses the
SConscript file in every subdirectory to find and compile all of the
gem5 source.</p>

<p>SCons automatically creates a <code class="highlighter-rouge">gem5/build</code> directory when first
executed. In this directory you’ll find the files generated by SCons,
the compiler, etc. There will be a separate directory for each set of
options (ISA and cache coherence protocol) that you use to compile gem5.</p>

<p>There are a number of default compilations options in the <code class="highlighter-rouge">build_opts</code>
directory. These files specify the parameters passed to SCons when
initially building gem5. We’ll use the X86 defaults and specify that we
want to compile all of the CPU models. You can look at the file
<code class="highlighter-rouge">build_opts/X86</code> to see the default values for the Scons options. You
can also specify these options on the command line to override any
default.</p>

<div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>scons build/X86/gem5.opt -j9
</code></pre></div></div>

<blockquote>
  <p><strong>gem5 binary types</strong></p>

  <p>The SCons scripts in gem5 currently have 5 different binaries you can
build for gem5: debug, opt, fast, prof, and perf. These names are
mostly self-explanatory, but detailed below.</p>

  <dl>
    <dt>debug</dt>
    <dd>Built with no optimizations and debug symbols. This binary is
useful when using a debugger to debug if the variables you need to
view are optimized out in the opt version of gem5. Running with
debug is slow compared to the other binaries.</dd>
    <dt>opt</dt>
    <dd>This binary is build with most optimizations on (e.g., -O3), but
with debug symbols included. This binary is much faster than
debug, but still contains enough debug information to be able to
debug most problems.</dd>
    <dt>fast</dt>
    <dd>Built with all optimizations on (including link-time optimizations
on supported platforms) and with no debug symbols. Additionally,
any asserts are removed, but panics and fatals are still included.
fast is the highest performing binary, and is much smaller than
opt. However, fast is only appropriate when you feel that it is
unlikely your code has major bugs.</dd>
    <dt>prof and perf</dt>
    <dd>These two binaries are build for profiling gem5. prof includes
profiling information for the GNU profiler (gprof), and perf
includes profiling information for the Google performance tools
(gperftools).</dd>
  </dl>

  <p>The main argument passed to SCons is what you want to build,
<code class="highlighter-rouge">build/X86/gem5.opt</code>. In this case, we are building gem5.opt (an
optimized binary with debug symbols). We want to build gem5 in the
directory build/X86. Since this directory currently doesn’t exist, SCons
will look in <code class="highlighter-rouge">build_opts</code> to find the default parameters for X86. (Note:
I’m using -j9 here to execute the build on 9 of my 8 cores on my
machine. You should choose an appropriate number for your machine,
usually cores+1.)</p>
</blockquote>

<p>The output should look something like below:</p>

<div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>Checking for C header file Python.h... yes
Checking for C library pthread... yes
Checking for C library dl... yes
Checking for C library util... yes
Checking for C library m... yes
Checking for C library python2.7... yes
Checking for accept(0,0,0) in C++ library None... yes
Checking for zlibVersion() in C++ library z... yes
Checking for GOOGLE_PROTOBUF_VERIFY_VERSION in C++ library protobuf... yes
Checking for clock_nanosleep(0,0,NULL,NULL) in C library None... yes
Checking for timer_create(CLOCK_MONOTONIC, NULL, NULL) in C library None... no
Checking for timer_create(CLOCK_MONOTONIC, NULL, NULL) in C library rt... yes
Checking for C library tcmalloc... yes
Checking for backtrace_symbols_fd((void*)0, 0, 0) in C library None... yes
Checking for C header file fenv.h... yes
Checking for C header file linux/kvm.h... yes
Checking size of struct kvm_xsave ... yes
Checking for member exclude_host in struct perf_event_attr...yes
Building in /local.chinook/gem5/gem5-tutorial/gem5/build/X86
Variables file /local.chinook/gem5/gem5-tutorial/gem5/build/variables/X86 not found,
  using defaults in /local.chinook/gem5/gem5-tutorial/gem5/build_opts/X86
scons: done reading SConscript files.
scons: Building targets ...
 [ISA DESC] X86/arch/x86/isa/main.isa -&gt; generated/inc.d
 [NEW DEPS] X86/arch/x86/generated/inc.d -&gt; x86-deps
 [ENVIRONS] x86-deps -&gt; x86-environs
 [     CXX] X86/sim/main.cc -&gt; .o
 ....
 .... &lt;lots of output&gt;
 ....
 [   SHCXX] nomali/lib/mali_midgard.cc -&gt; .os
 [   SHCXX] nomali/lib/mali_t6xx.cc -&gt; .os
 [   SHCXX] nomali/lib/mali_t7xx.cc -&gt; .os
 [      AR]  -&gt; drampower/libdrampower.a
 [   SHCXX] nomali/lib/addrspace.cc -&gt; .os
 [   SHCXX] nomali/lib/mmu.cc -&gt; .os
 [  RANLIB]  -&gt; drampower/libdrampower.a
 [   SHCXX] nomali/lib/nomali_api.cc -&gt; .os
 [      AR]  -&gt; nomali/libnomali.a
 [  RANLIB]  -&gt; nomali/libnomali.a
 [     CXX] X86/base/date.cc -&gt; .o
 [    LINK]  -&gt; X86/gem5.opt
scons: done building targets.
</code></pre></div></div>

<p>When compilation is finished you should have a working gem5 executable
at <code class="highlighter-rouge">build/X86/gem5.opt</code>. The compilation can take a very long time,
often 15 minutes or more, especially if you are compiling on a remote
file system like AFS or NFS.</p>

<h2 id="common-errors">Common errors</h2>

<h3 id="wrong-gcc-version">Wrong gcc version</h3>

<div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>Error: gcc version 4.8 or newer required.
       Installed version: 4.4.7
</code></pre></div></div>

<p>Update your environment variables to point to the right gcc version, or
install a more up to date version of gcc. See
building-requirements-section.</p>

<h3 id="python-in-a-non-default-location">Python in a non-default location</h3>

<p>If you use a non-default version of Python, (e.g., version 2.7 when 2.5
is your default), there may be problems when using SCons to build gem5.
RHEL6 version of SCons uses a hardcoded location for Python, which
causes the issue. gem5 often builds successfully in this case, but may
not be able to run. Below is one possible error you may see when you run
gem5.</p>

<div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>Traceback (most recent call last):
  File "........../gem5-stable/src/python/importer.py", line 93, in &lt;module&gt;
    sys.meta_path.append(importer)
TypeError: 'dict' object is not callable
</code></pre></div></div>

<p>To fix this, you can force SCons to use your environment’s Python
version by running <code class="highlighter-rouge">python `which scons` build/X86/gem5.opt</code> instead
of <code class="highlighter-rouge">scons build/X86/gem5.opt</code>. More information on this can be found on
the gem5 wiki about non-default Python locations: <a href="http://www.gem5.org/Using_a_non-default_Python_installation">Using a non-default
Python
installation</a>.</p>

<h3 id="m4-macro-processor-not-installed">M4 macro processor not installed</h3>

<p>If the M4 macro processor isn’t installed you’ll see an error similar to
this:</p>

<div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>...
Checking for member exclude_host in struct perf_event_attr...yes
Error: Can't find version of M4 macro processor.  Please install M4 and try again.
</code></pre></div></div>

<p>Just installing the M4 macro package may not solve this issue. You may
nee to also install all of the <code class="highlighter-rouge">autoconf</code> tools. On Ubuntu, you can use
the following command.</p>

<div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>sudo apt-get install automake
</code></pre></div></div>

  <br>

  <!-- RETRIVE PREVIOUS PAGE LINK -->
  
    
  
    
  
    
  
    
  

  <!-- RETRIEVE NEXT PAGE LINK -->
  
    
  
    
  
    
  
    
  


  <div class="navbuttons">
    
      <a href=""><button type="button" class="btn btn-outline-primary">PREVIOUS</button></a>
    

    
      <a href=""><button type="button" class="btn btn-outline-primary">NEXT</button></a>
    
  </div>
</div>

	</main>
	<footer class="page-footer">
	<div class="container">
		<div class="row">

			<div class="col-12 col-sm-4">
				<p>gem5</p>
				<p><a href="/about">About</a></p>
				<p><a href="/publications">Publications</a></p>
				<p><a href="/contributing">Contributing</a></p>
				<p><a href="/governance">Governance</a></p>
			<br></div>

			<div class="col-12 col-sm-4">
				<p>Docs</p>
				<p><a href="/documentation">Documentation</a></p>
				<p><a href="http://gem5.org/Documentation">Old Documentation</a></p>
				<p><a href="https://gem5.googlesource.com/public/gem5">Source</a></p>
			<br></div>

			<div class="col-12 col-sm-4">
				<p>Help</p>
				<p><a href="/search">Search</a></p>
				<p><a href="/mailing_lists">Mailing Lists</a></p>
				<p><a href="https://gem5.googlesource.com/public/gem5-website/+/refs/heads/master/README.md">Website Source</a></p>
			<br></div>

		</div>
	</div>
</footer>


	<script src="https://code.jquery.com/jquery-3.3.1.slim.min.js" integrity="sha384-q8i/X+965DzO0rT7abK41JStQIAqVgRVzpbzo5smXKp4YfRvH+8abtTE1Pi6jizo" crossorigin="anonymous"></script>
	<script src="https://cdnjs.cloudflare.com/ajax/libs/popper.js/1.14.3/umd/popper.min.js" integrity="sha384-ZMP7rVo3mIykV+2+9J3UJ46jBk0WLaUAdn689aCwoqbBJiSnjAK/l8WvCWPIPm49" crossorigin="anonymous"></script>
	<script src="https://stackpath.bootstrapcdn.com/bootstrap/4.1.3/js/bootstrap.min.js" integrity="sha384-ChfqqxuZUCnJSK3+MXmPNIyE6ZbWh2IMqE241rYiqJxyMiZ6OW/JmZQ5stwEULTy" crossorigin="anonymous"></script>
	<script src="https://unpkg.com/commentbox.io/dist/commentBox.min.js"></script>

	<script>
	  // When the user scrolls down 20px from the top of the document, show the button
	  window.onscroll = function() {scrollFunction()};

	  function scrollFunction() {
	      if (document.body.scrollTop > 100 || document.documentElement.scrollTop > 20) {
	          document.getElementById("myBtn").style.display = "block";
	      } else {
	          document.getElementById("myBtn").style.display = "none";
	      }
	  }

	  // When the user clicks on the button, scroll to the top of the document
	  function topFunction() {
	      document.body.scrollTop = 0;
	      document.documentElement.scrollTop = 0;
	  }

		import commentBox from 'commentbox.io';
		// or
		const commentBox = require('commentbox.io');
		// or if using the CDN, it will be available as a global "commentBox" variable.

		commentBox('my-project-id');

	</script>

</body>


</html>
